General UI Components
Here's the general information about the misc. UI components listed below.
AccordionBox
General Design Considerations
Here’s when and why we use accordion boxes:
- Default state can be expanded or collapsed depending on how the designer wants to scaffold the user interaction. A closed panel can be used to keep the default opening condition of sim from being visually overwhelming, and suggesting a logical route for exploration, for example in Build an Atom and in GE:B (please spell out simulation name).
- Accordion boxes can also be useful for teachers to ask predictive questions.
- Can contain non-interactive readouts, interactive controls, but not sprites (e.g., draggable toolbox items).
Note this design pattern covers multiple PhET Component Types
Aesthetic Considerations
- If space is a concern, the title can be hidden while the accordion box is expanded. Note that an accessible name for the title is always needed and available for the non-visual experience.
- An expanded accordion box cannot overlap other elements when opened (unlike combo box, for instance).
- Always includes an iconed button (+/-), typically to the left of the title.
- Other sim content does not fill the space when an accordion box is collapsed.
- The accordion box content can be expanded or collapsed by default and a change of state for one accordion does not affect the state of other accordion boxes.
Accessibility Considerations
Accessible Components of an Accordion Box
Adapted from: ARIA Pracrices 1.1, section 3.1 Accordion
- Accordion Header: Label (usually a heading with a +/- icon signalling expand/collapse behaviour) for a section of content (usually a collapsible box). The accordion header could also be an icon, alone. The accordion header serves as a control that can show or hide a section of content.
Accordion Panel: Section of content (e.g., the content box) associated with an accordion header
Typically, has a visual title with an icon that indicates expanded and collapsed state.
- The title may disappear when box is expanded.
- Focus highlight would go around title in both the expanded and collapsed states, if title remains visible.
- If title visually disappears when expanded, the focus highlight would be limited to the open/close icon and the designer would need to consider extra padding to ensure a reasonable clickable area.
- It is possible that the focus highlight can change size when toggling between expanded/collapsed states in the scenario when the expanded box does not have a title.
- The typical structure is a
buttonnested within the parent titling element, likely a heading. - Typically, the open/close icon does not need to be represented in the Parallel DOM.
- For accessibility the expanded and collapsed states of the box are communicated through a combination of ARIA
attributes,
aria-expanded,aria-controls,aria-hiddenthat have to be managed through javascript.
Gesture Support
ToDO.
Keyboard Support
Adapted from: ARIA Pracrices 1.1, section 3.1 Accordion
| Key | Function |
|---|---|
| Enter or Space | When focus is on the accordion header of a collapsed section, expands or collapses the accordion panel. |
| Down Arrow (optional) | - If focus is on an accordion header, moves focus to the next accordion header. If focus is on the last accordion header, either does nothing or moves focus to the first accordion header. - If there is only one accordion, doing nothing with focus is likely appropirate. |
| Up Arrow (Optional) | - If focus is on an accordion header, moves focus to the previous accordion header. If focus is on the first accordion header, either does nothing or moves focus to the last accordion header. - If there is only one accordion, doing nothing with focus is likely appropirate. |
| Home and End (Optional) | Likely only relevant if there are several to many accordions (to discuss) |
| Control + Page Down and Control + Page Up (Optional) |
Behave the same way as Up and Down Arrows. (to discuss) |
QUESTION: It's not clear to me how users get inside a panel, if the panel has no focusable items.
Management of Role, Property, State, and Tabindex Attributes
Adapted from: ARIA Pracrices 1.1, section 3.1 Accordion
| Role | Attribute | Element | Usage | Notes |
|---|---|---|---|---|
| -- | -- | button | The title content of each accordion header is contained in an element with role button. | |
| -- | -- | h3 (or appropriate level) |
PhET Sims use native HTML, so we use native heading and button elements to create the accordion header. | The button element is the only element inside the heading element. That is, if there are other visually persistent elements, they are not included inside the heading element. |
| - | aria-expanded="true/false" |
div | Added to accordion panel dynamically with Javascript to indicate when the panel associated with the header is visible (aria-expanded="true"), or if the panel is not visible, aria-expanded is set to false. |
|
| - | aria-controls="[ID REF of element containing accordion panel]" | Not in the PhET implementation, as it is not needed, and may not be widely supported anyways. | ||
| button | - | |||
| - | aria-disabled="true" | - | If the accordion panel associated with an accordion header is visible, and if the accordion does not permit the panel to be collapsed, the header button element has aria-disabled set to true. (I think this is NOT RELEVANT for PhET sims?) |
|
| region (optional) | aria-labelledby=[ID REF of button that controls the display of the panel] |
div |
- |
DRAFT: Sample HTML
<! -- expanded state -->
<h3>
<button id="accordion-header-01" aria-expanded="true">Factors</button>
</h3>
<div id="accordion-panel-01" role="region" aria-labelledby="accordion-header-01">
<p>Box content.</p>
<p>More content or even other HTML controls.</p>
</div>
<! -- collapsed state -->
<h3>
<button id="accordion-header-02" aria-expanded="false">Product</button>
</h3>
<div id="accordion-panel-02" role="region" aria-labelledby="accordion-header-02" aria-hidden="true">
<p>Box content.</p>
<p>More content or even other HTML controls.</p>
</div>
Supporting Accessibility Resources
Design Doc Content Template Text
Accordion Box
- Accordion Box Title (header):
- Accessible Name: content for the accordon box title
- Header contains a title? Yes/No, default Yes - actually, title for header should be required.
- Title is a heading? Yes/No, defaults to Yes
- If title is heading, set heading level, defaults to H3
- Accordion title is visually hidden: Yes/No (defaults to No)
- Accordion Box Content (panel):
- Parent container accordion box contents: defaults to a div
- Use same convention as other objects and controls.
- Default open state: expanded/collapsed (defaults to expanded)
Sim Examples
Checkbox
General Design Considerations
Here’s the when and why we use a checkbox (traditional looking checkbox user interface component) in simulation design.
- Generally, when a secondary or non-essential option needs to be toggled between on and off states
- To toggle more than one option in a group of options
- Checkboxes are often used to allow users to layer on more complex representations, or to view multiple, related represenations simultaneously. More complex options are generally off by default.
Note this design pattern covers multiple PhET Component Types
- Question: Are there any other types of visual checkboxes?
Aesthetic Considerations
- Checkbox appears checked or not checked on simulation load
- Appears with a text-based label, or an icon as the label, or a combination of both text and icon
- Title case is used for text-based labels for checkboxes
Accessibility Considerations
- HTML checkboxes (i.e.,
input type="checkbox") and possibly all visual PhET sim checkboxes are two-state controls that represent the element's "checkedness" state. - Traditional looking checkboxes with visual labels are generally best represented in the PDOM as an
inputof type checkbox with an associatedlabelelement. - When the visual label content is an image or a string of text that does immediately translate into a name that clearly
communicates what the checkbox is for, non-visually, consider changing the visual string, adding clarifying help text,
or providing a more descriptive name as the
labelelement's content in the PDOM. Keep in mind that ideally, the visual text and the text in the PDOM should be the same to support users who use voiced commands. - Groups of related checkboxes may benefit from being explicitly grouped using a containing element (e.g.,
fieldsetordiv) with the ARIArole="group". Grouping checkboxes is optional. - Explicitly grouped checkboxes may benefit from a group name provided by either an
h3or alegend. - Checkboxes that appear visually grouped (e.g., by proximity or with a visual box) for convenience or space-saving may not benefit from explicit group semantics in the PDOM.
- When a group is very important, consider using a heading, e.g.,
h3as headings are placed in the heading outline which can be navigated with screen reader software whereas thelegendelement is not placed in the heading hierarchy.
Note: Known issue that some screen readers (i.e., VoiceOver) repeat the checkbox's label content when the label is
associated with the input via the for attribute. We discovered that we do not get repetition of the label content
when the label comes before the checkbox. When there is no visible screen label, the aria-label attribute is an
option, and it also does not cause any repetition.
Gesture Support
ToDO.
Keyboard Support
| Key | Function |
|---|---|
| Tab | Moves keyboard focus to the checkbox. |
| Space | Toggles checkbox between checked and unchecked states. |
Management of Role, Property, State, and Tabindex Attributes
Respecting the first rule of ARIA, "use a native HTML element whenever possible", we use native checkbox elements in the PDOM to represent traditional looking checkbox interactions. An HTML checkbox could represent other "switching" interactions that may not visaully look like a checkbox in the simulation, but examples for those are provided elsewhere. Because we use native HTML for checkbox interactions, some of the guidance provided in ARIA Practices for checkbox widgets is not relevant. I have adapted the content from the ARIA practices section for checkbox.
- No explicit ARIA role of checkbox is needed on an native HTML checkbox (
input type="checkbox"). - No
tabindexrequired, native HTML checkboxes are focusable elements. - An HTML checkbox has an accessible label (i.e., accessible name) provided by one of two of the following ways:
- Visible text content contained within a
labelelement and assocaited to itsinputwith theforattribute. - Content within an
aria-labelattribute set on theinputelement withtype="checkbox".
- Visible text content contained within a
- When checked, the checkbox element has the attribute
checkedpresent. - When not checked, the
checkedattribute is not present. - When partially checked, it has state
aria-checkedset tomixed. (tri-state checkboxes only) - When a set of checkboxes is presented as a logical group with a visible label, the checkboxes are included in an
element with
role="group"that has the propertyaria-labelledbyset to the ID of the element containing the label or name for the group. - When the presentation includes additional descriptive static text (i.e., help text) relevant to a checkbox or group of
checkboxes, using
aria-describedbyis an option to provide automatically read help text. We have, however, that automatic helptext is not needed in our sims. Users seem to prefer on-demand help text.
Simplified HTML Examples for PDOM
Options for Checkbox in the A11y API
When creating the common code component, it would be useful to have options to use either a label element or
an aria-label attribute to provide the accessible name for the checkbox.
Checkbox with visual label text
Energy Forms and Changes
Visual checkbox with a text-based label:

State Descriptions
<input id=”energy-symbols” type=”checkbox”> <!-- not checked checkbox-->
<label for=”energy-symbols”>Energy Symbols</label>
<p>Observe energy chunks move and change through system.</p>
Responsive Descriptions
- When checked: Symbols flow with energies.
- When unchecked: Energy symbols hidden.
Checkbox without visual label text (option with aria-label)
Area Model Introduction
Visual checkbox with different label

<input id="counting-numbers" type="checkbox" aria-label="Counting numbers">
<p>Use area grid with or without counting numbers in grid cells.</p>
Unnamed group of checkboxes
Gravity Force Lab
Note: still need to finish this example.
<input id=”” type=”checkbox”> <!-- not checked checkbox-->
<label for=””>Constant Size</label>
<p>When changing mass, observe constant or changing size of spheres.</p>
<input id=”” type=”checkbox”> <!-- not checked checkbox-->
<label for=””>Force Values</label>
<p>Explore value of forces in newtons.</p>
<input id=”” type=”checkbox”> <!-- not checked checkbox-->
<label for=””>Scientific Notation</label>
<p>Listen to newtons in scientific notation.</p>
Supporting Accessibility Resources
- Using ARIA, working draft
- HTML5.1, Section 4.10.5.1.15. Checkbox state
- ARIA Practices 1.1 Section 3.6 Checkbox
Checkbox Snippet for Design Document
{{checkbox name}}, checkbox
- Accessible Name:
- Interaction Type: checkbox or non-visual checkbox
- Initial State: checked/ not checked
- (Optional) Help Text:
- (Optional) Context responses or link to section with context responses.
- (Optional) Design Note: Special things about this checkbox, if any.
Sim Examples
ComboBox
General Design Considerations
- Generally used with limited space and/or a long list of choices
- PhET comboboxes are not auto-select when hovering options with a mouse or when navigating through options with the arrow keys (i.e., different from radio button lists)
- Label for control serves a dual purpose: identifies the combobox (list of options) and identifies the selected option
- Selected item is communicated clearly upon focus and when the list is closed
- Large pointer/click areas: box label and selected item; option labels and images
Aesthetic Considerations
- List can appear above or below the button depending on space considerations
- Can include an indicator image (to the left of the list item)
- The rounded corners of the list should match the rounded corners of the button
- Generally, the list panel is often the same width as the button
- Mouse hover and focus highlights should be considered together
Accessibility
The PhET combobox interaction, visually looks and behaves as a combobox in the sense that a list of hidden options can
be revealed on demand; however, the accessible representation that we have found to work nicely is actually a button,
which may have a dynamic label (i.e., accessible name) that pops up a listbox with a list of options. Design and
interaction details are below.
Gesture Support
ToDO.
Keyboard Support
| Key | Function |
|---|---|
| Enter and Space | If the listbox is NOT displayed, opens/expands the listbox and moves focus to selected option in the opened list. (Note Space key is not specified in the standard, but that's how our example and the W3C example work. Space key works on a button, but not specifically on a list.) |
| Enter | If the listbox is displayed, selects item and collapses the listbox and moves focus to the button. |
| Escape | If the listbox is displayed, collapses the listbox without changing the slection and moves focus to the button. |
| Down Arrow | Moves focus to the next option. |
| Up Arrow | Moves focus to the previous option. |
| Home (Optional) | Moves focus to first option. (Recommended when there are more than 5 items) |
| End (Optional) | Moves focus to last option. (Recommended when there are more than 5 items) |
Role, Property, State, and Tabindex Attributes
(adjusted content from W3C listbox collapsible example, see https://www.w3.org/TR/wai-aria-practices-1.1/examples/listbox/listbox-collapsible.html)
| Role | Attribute | Element | Usage |
|---|---|---|---|
| - | aria-haspopup="listbox" |
button |
Indicates that activating the button displays a listbox (i.e., a list of options) |
| - | aria-expanded="true" |
button |
Set by the JavaScript when the listbox is displayed. Otherwise, is not present. |
| - | aria-labelledby="listbox-static-label listbox-option-dynamic-label" |
button | Reads out a combined name for the interaction when focus is placed on the button, first the name for the "combobox interaction", then the name of the selected option. Javascript sets the inner content of the button to be the selected item. |
role="listbox" |
- | ul |
Identifies the focusable element that has listbox behaviors and contains the listbox options. |
| - | aria-labelledby="listbox-static-label" |
ul | Refers to the element containing the listbox label (i.e., the accessible name for the listbox). |
| - | tabindex="-1" |
ul | - Makes the listbox focusable. - The JavaScript sets focus on the listbox when the listbox is displayed. |
| - | aria-activedescendent |
- | - Set by the JavaScript when the listbox is displayed and sets focus on the listbox; otherwise is not present. - Refers to the option in the listbox that is visually indicated as having keyboard focus. - When navigation keys, such as Down Arrow, are pressed, the JavaScript changes the value. - Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the ul element. |
role="option" |
- | li |
Identifies each selectable element containing the name of an option. |
| - | aria-selected="true" |
li |
- Indicates that the option is selected. - Applied to the element with role option that is visually styled as selected. - Set by the Javascript when Enter is pressed on the option referenced by aria-activedescendant. - Note that in an auto-select listbox where selection follows focus, the option with this attribute is always the same as the option that is referenced by aria-activedescendant. |
Sample HTML for Combobox
The PhET combobox interaction, visually looks and behaves as a combobox; however, the ARIA 1.1 Combobox design pattern
wasn't and will never be supported. For the accessible representation in the Parallel DOM we implemented this widget as
a dynamic button and a popped-up listbox (Bryan Garanventa, 2016). The HTML example is below.
Note: The HTML for this interaction may change when the ARIA role combobox has better support accross assitive
technologies.
Molarity Example (10 options)
<div tabindex="-1" id="container-for-labels">
<span id="listbox-static-label">Solute</span>
<button id="listbox-option-dynamic-label" tabindex="0" aria-haspopup="listbox" aria-labelledby="listbox-static-label listbox-option-dynamic-label">Drink Mix</button>
</div>
<ul role="listbox" tabindex="0" id="listbox" aria-activedescendant="option-1" aria-labelledby="listbox-static-label" style="list-style:none;">
<li role="option" id="option-1" class="selected" aria-selected="true">Drink mix</li>
<li role="option" id="option-2">Cobalt (II) nitrate</li>
<li role="option" id="option-3">Cobalt Chloride</li>
<li role="option" id="option-4">Potassium dichromate</li>
<li role="option" id="option-5">Gold (III) chloride</li>
<li role="option" id="option-6">Potassium chromate</li>
<li role="option" id="option-7">Nickel (II) chloride</li>
<li role="option" id="option-8">Copper sulfate</li>
<li role="option" id="option-9">Potassium permanganate</li>
<li role="option" id="option-10">Potassium dichromate</li>
</ul>
<!-- help text for combobox -->
<p>Change a solute and observe differences.</p>
Supporting Accessibility Resources
- Adapted from ARIA Practices Collapsible Listbox Example( 2016)
- The above pattern has been adopted as the 1.2 Combobox design pattern( 2022)
Design Doc Content Template Text
{{Name of combobox}}, combobox
Accessible Name (dynamic): Text + {{Name of Selected list item}} (e.g. Solute: {{Drink Mix}})
Interaction Type: Combobox (i.e., Combobox.ts composed of subcomponents ComboBoxButton.ts (tagName: 'button')
and ComboBoxListBox.ts (ariaRole: 'listbox')
Button Label with initial selection:
Listbox list items:
- List Item 1 (e.g., Drink Mix)
- List Item 2 (e.g., Cobalt (II) nitrate)
- List Item 3
(Optional) Help Text:
(Optional) Link to section with object & context responses
(Optional) Design Note: Special things about this combobox, if any.
Sim Examples
RectangularRadioButtonGroup
No markdown content for RectangularRadioButtonGroup yet.